﻿/* **
 * WebQ - a Web Questionare / Survey Framework
 * Andrew Adhi Ariane Murniadi / 2009
 * GPL
 * $Id$
 *									** */

using System;
using System.Collections.Generic;
using System.Text;
using System.Web.UI;

namespace WebQ.Core {
	/// <summary>
	/// Basic class where all visualizer should derive from. This class provides basic functionalities
	/// and framework on control creation as well as answer extraction from postbacked data
	/// </summary>
	/// <remarks>Visualizers are entities that is responsible on presentation of the QAItem. During the
	/// course of development it was thought that it perfectly makes sense for the visualizer to also
	/// handles the answer extraction process because the Visualizer knows what is the expected answer is.
	/// </remarks>
	public abstract class WebQVisualizer {
		private WebQIdGenerator m_generator = null;
		private WebQVisualizerConfiguration m_conf = null;

		/// <summary>
		/// Constructor
		/// </summary>
		/// <param name="generator">Unique Id Generator</param>
		/// <param name="conf">Configuration for the visualizer</param>
		/// <remarks>The generator parameter is subject to reconsideration. Probably defering the
		/// need for this generator to the last moment is better</remarks>
		//Todo: Rethink generator parameter
		public WebQVisualizer ( WebQIdGenerator generator, WebQVisualizerConfiguration conf ) {
			m_generator = generator;
			m_conf = conf;
		}

		/// <summary>
		/// Returns a collection of controls that the Visualizer produces to represent the 
		/// QAItem.
		/// </summary>
		/// <param name="entity">The entity to represent</param>
		/// <returns>Collection of controls</returns>
		public virtual List<Control> GetChildControls ( WebQQAItem entity ) {
			m_generator.BaseId = entity.Id;
			m_generator.Reset ();
			return CreateChildControls ( entity, m_generator, m_conf );
		}

		/// <summary>
		/// Extract the answer(s) from the postbacked data and set it to the entity
		/// </summary>
		/// <param name="entity">entity where the answer should be set to</param>
		/// <param name="postbackedData">postbacked data where the answers contained</param>
		public virtual void ExtractAnswers ( WebQQAItem entity, Dictionary<String, String> postbackedData ) {
			m_generator.BaseId = entity.Id;
			m_generator.Reset ();
			SetAnswers ( entity, m_generator, m_conf, postbackedData );
		}

		/// <summary>
		/// To be implemented in derived classes. The method should create the needed controls
		/// </summary>
		/// <param name="entity">item to be represented by the visualizer</param>
		/// <param name="generator">Id Generator for generating client id controls</param>
		/// <param name="conf">The configuration for the visualizer</param>
		/// <returns>List of controls that represents the QAItem</returns>
		protected abstract List<Control> CreateChildControls ( WebQQAItem entity, WebQIdGenerator generator, WebQVisualizerConfiguration conf );

		/// <summary>
		/// To be implemented in derived classes. The method should identify answers and set them to the 
		/// appropriate entity
		/// </summary>
		/// <param name="entity">item where the answers are to be set to</param>
		/// <param name="generator">client id generator</param>
		/// <param name="conf">configuration of the visualizer</param>
		/// <param name="postbackedValues">list of postbacked values</param>
		protected abstract void SetAnswers ( WebQQAItem entity, WebQIdGenerator generator, WebQVisualizerConfiguration conf, Dictionary<String, String> postbackedValues );
	}
}
